.. _example-predominance-01: 01 - Analytic Function Predominance =================================== A predominance diagram colours a plane by *which* of several quantities is largest at each point. In geochemistry those quantities are species activities and the plane is usually pH against pe, but the machinery has nothing to do with chemistry, and here it is run on three algebraic functions so that it can be seen working on its own. The example also does the same job twice, by two different strategies, and the interesting number is how much work each one needed. Three functions --------------- The *Function Model* defines three expressions of ``x`` and ``y``: .. code-block:: text f1 = x*x + y*0.5 f2 = -x*x - y*0.5 f3 = -x + y At every point one of the three is the largest, and the diagram is the map of which. ``f1`` and ``f2`` are each other's negatives, so one of them is positive wherever the other is negative, and ``f3`` is a plane cutting across both. The boundaries are therefore curves, not straight lines -- enough structure to be worth drawing, simple enough to check by hand. A *Predominance Study* is told which expressions compete, by name and with the label each region should carry. Nothing else distinguishes them: a predominance study is a comparison, and what it compares is up to you. Two ways to find the same boundaries ------------------------------------ Both studies cover :math:`x, y \in [-1, 1]` with 15 divisions each way. A **Grid Study** does the obvious thing: it evaluates every node of the lattice. The result is complete and the cost is fixed -- 225 evaluations here, and the same 225 whether the diagram turns out to be intricate or a single region. A **Predominance Study** works differently. It starts coarse, finds where the winner changes, and spends its remaining evaluations following those boundaries rather than filling in the interiors. It used **132** evaluations for this diagram: a little over half. The saving is what makes the method worth having, and it scales with the cost of one evaluation. Here each is an arithmetic expression and nobody cares. When each node is a PHREEQC simulation -- as in every other example in this set -- the difference between 225 runs and 132 is the difference between a diagram you can iterate on and one you set going and leave. The two diagrams ---------------- .. figure:: UsingGridStudy.svg :alt: Predominance diagram from the full 15 by 15 grid, with all 225 computed points marked :align: center From the grid study. The computed points are drawn on top of the regions, and they are the whole lattice, evenly spaced -- including deep inside regions where the answer was never in doubt. .. figure:: UsingPredom_pnt_Study.svg :alt: The same diagram from the tracking study, with points concentrated along the boundaries :align: center From the predominance study. The same regions, the same boundaries, and the points now crowded along the edges where the winner changes, sparse elsewhere. The regions between them are interpolated. Put side by side, the two pictures are the argument for the method: the answer is in the boundaries, so that is where the effort should go. A caveat -------- Interpolation between tracked points assumes the boundary behaves between them. A region too small for the initial coarse pass to notice can be missed entirely, and the diagram will not look wrong -- it will look clean. Where a result matters, a grid study is the check, which is one reason this example keeps both. Try it ------ * Raise the divisions on both studies and watch the grid's cost grow as the square while the tracking study's grows roughly with the length of the boundaries. * Add a fourth function and see how the diagram and the point count change. * Replace ``f3`` with something that wins only in a small corner, then compare what the two studies find.